/** Copyright (C) 2012 Foxit Corporation. 
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.
 * Without SDK license agreement, you cannot redistribute anything.
 * Functions in this header file, require "FPDFVIEW" module to be enabled in your SDK license.
 *
 * @file	fpdfpage.h
 * @brief	Header file for the View module.
 * @details	The view module offers:
 *			1. Methods for basic rendering of pages.
 *			2. Methods for retrieving datas from a page and other related operations.
 *			3. Methods for operating fonts.
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling PDF object module explicitly.
 */
  
 /** 
 * @addtogroup PDFPAGE PDF Page 
 * @brief Methods in this module are included in fpdfpage.h 
 */
/** @{*/

#ifndef __FGSPDFPAGE__
#define __FGSPDFPAGE__

#ifndef __FGSPDFBASE__
    #include "fpdfbase.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief	Get the page mode of the document, which specifies how the document should be displayed when opened. 
 *
 * @param[in] document		Reference to a document.
 *
 * @return	The page mode of the document. See macro definitions <b>FGSPDFPageMode</b>.
 */
FGSPDFPageMode FGSPDFPageGetPageMode(FGSPDFDocumentRef document);

/**
 * @brief	Get the count of pages in the document.
 * 
 * @param[in] document		Reference to a document.
 *
 * @return	The count of the pages in the specific document.
 *			
 */
SInt32 FGSPDFPageGetPageCount(FGSPDFDocumentRef document);

/**
 * @brief	Load the specified page.
 *
 * @param[in] document		Reference to a document.
 * @param[in] index			A zero-based index of the page which is to be loaded.
 *
 * @return	The loaded page Reference.
 *
 */
FGSPDFPageRef FGSPDFPageLoadPage(FGSPDFDocumentRef document, SInt32 index);

/**
 * @brief Close a page and release all related resources.
 *
 * @param[in] page		A page reference.
 *
 * @return	::kFGSErrorSuccess means parsing the page successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFPageClosePage(FGSPDFPageRef page);

/**
 * @brief	Get the current page index.
 *
 * @param[in] page          Reference to a page.
 *
 * @return	The page idnex.
 *
 */
SInt32 FGSPDFPageGetPageIndex(FGSPDFPageRef page);

/**
 * @brief Start parsing a page, so it can be rendered or searched.
 *
 * @details Parsing is a progressive process. This function starts the parsing process,
 *			and may return before the parsing is finished, if a ::FGSPause structure is provided.<br>
 *			Application should call ::FGSPDFPageContinueParsingPage repeatedly to finish the parsing
 *			when return value is ::kFGSErrorToBecontinued.<br>
 *			There can be only one parsing procedure active for a page, and if a page
 *			has already been parsed, you can't start a parsing again.
 *
 * @param[in] page			Reference to a page.
 * @param[in] text_only		A boolean value used to decide whether to parsing texts only (used for searching) or not.
 * @param[in] pause			A ::FGSPause structure that can pause the parsing process.
 *							Or <b>NULL</b> if you don't want to pause the process.
 *
 * @return	::kFGSErrorSuccess means parsing the page successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFPageStartParsingPage(FGSPDFPageRef page, Boolean text_only, FGSPause *pause);

/**
 * @brief Continue parsing the page.
 *
 * @details ::FGSPDFPageStartParsingPage should be called first before render the page or search on the page.
 *			Application should call ::FGSPDFPageContinueParsingPage repeatedly to finish the parsing
 *			when its return value is ::kFGSErrorToBecontinued.
 *
 * @param[in] page			Reference to a page.
 * @param[in] pause			A ::FGSPause structure that can pause the parsing process.
 *							Or <b>NULL</b> if you don't want to pause the process.
 *
 * @return	::kFGSErrorSuccess means parsing the page successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFPageContinueParsingPage(FGSPDFPageRef page, FGSPause *pause);

/**
 * @brief Get an estimated parsing progress in percentage.
 *
 * @param[in] page			Reference to a Page.
 *
 * @return  An integer between 0 and 100 (inclusive) indicating the parsing progress.
 *			The result is just a rough estimation.<br>
 *			-1 means parameter error.
 */
SInt32 FGSPDFPageGetParsingPageProgress(FGSPDFPageRef page);

/**
 * @brief Get the size of a page
 *
 * @param[in] page			Reference to a page.
 *
 * @return	The size of the page
 *
 */
CGSize FGSPDFPageGetPageSize(FGSPDFPageRef page);

/**
 * @brief Get the displayable area (bounding box) of a page.
 *
 * @param[in] page			Reference to a page.
 *
 * @return	The rectangle of the bounding box.
 *
 */
CGRect FGSPDFPageGetPageBBox(FGSPDFPageRef page);

/**
 * @brief Get the content margin of a page.
 *
 * @param[in] page			Reference to a Page.
 * @param[out] rect			Pointer to a RectF that receives the margin.
 * @param[in] backcolor		A color for intended background in the page, in the format 0xRRGGBB.
 *
 * @return	RtBaseDef.ERR_SUCCESS means get the content margin successfully.<br>
 *			For more definitions please see definitions <b>RtBaseDef.ERR_XXX</b>.
 */
CGRect FGSPDFPageGetPageContentMargin(FGSPDFPageRef page, UInt32 backcolor);

/**
 * @brief Get page transformation matrix from page coordinates to device coordinates.
 *
 * @param[in] page			Reference to a page.
 * @param[in] rect			The rect of the display area in the device coordination
 * @param[in] rotate		The page orientation: <br>
 *							<ul>
 *							<li>0: normal</li>
 *							<li>1: rotated 90 degrees clockwise</li>
 *							<li>2: rotated 180 degrees</li>
 *							<li>3: rotated 90 degrees counter-clockwise</li>
 *							</ul>
 *
 * @return	Page transformation matrix.
 *
 */
CGAffineTransform FGSPDFPageGetPageDisplayingMatrix(FGSPDFPageRef page, CGRect rect, SInt32 rotate);

/**
 * @brief Start drawing a quick preview of a page.
 *
 * @details It's often useful to present users a quick preview of a page, right after the
 *			page is parsed. This preview renders only a limited set of easy features in the
 *			page, so it'll be rather quick to finish this process.
 *
 * @param[in] bitmapContext	Reference to a bitmap context, as the rendering device.
 * @param[in] page			Reference to a page. The page has to be parsed first.
 * @param[in] matrix		The transformation matrix from page coordinates to device coordinates.
 * @param[in] rotate		The page orientation: <br>
 *							<ul>
 *							<li>0: normal</li>
 *							<li>1: rotated 90 degrees clockwise</li>
 *							<li>2: rotated 180 degrees</li>
 *							<li>3: rotated 90 degrees counter-clockwise</li>
 *							</ul>
 * @param[in] flags			This is reserved and it must be zero.
 * @param[in] pause			Reference to a ::FGSPause structure that can pause the rendering process.
 *							This can be <b>NULL</b> if no pausing is needed.
 * @param[out] renderer		Reference to a render used to continue rendering if the function return kFGSErrorToBecontinued.
 *
 * @return	::kFGSErrorSuccess means quickdraw successfully finished.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
//FGSErrorRet FGSPDFPageStartQuickDrawRenderingPage(CGContextRef bitmapContext, FGSPDFPageRef page,
//                                         CGAffineTransform *matrix, SInt32 rotate, SInt32 flags, FGSPause *pause, FGSDPRenderRef *renderer);
FGSErrorRet FGSPDFPageStartQuickDrawRenderingPage(CGContextRef bitmapContext, FGSPDFPageRef page,
                                                  CGAffineTransform *matrix, SInt32 flags, FGSPause *pause, FGSDPRenderRef *renderer);

/**
 * @brief Continue a quick draw processing
 *
 * @param[in] page			Reference to a page. The page has to be parsed first.
 * @param[in] renderer		Reference to a render get form FGSPDFPageStartQuickDrawRenderingPage.
 * @param[in] pause			Reference to a ::FGSPause structure that can pause the rendering process.
 *							This can be <b>NULL</b> if no pausing is needed.
 *
 * @return	::kFGSErrorSuccess means quickdraw successfully finished.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFPageContinueQuickDrawRendingPage(FGSPDFPageRef page, FGSDPRenderRef renderer, FGSPause *pause);

/**
 * @brief Stop a quick draw processing
 *
 * @param[in] page			Reference to a page. The page has to be parsed first.
 * @param[in] renderer		Reference to a render get form FGSPDFPageStartQuickDrawRenderingPage.
 *
 * @return	::kFGSErrorSuccess means stop the quick draw processing successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet	FGSPDFPageStopQuickDrawRenderingPage(FGSPDFPageRef page, FGSDPRenderRef renderer);

/**
 * @brief Create renderer with bitmap for a page.
 *
 * @details The renderer is used for setRenderingPageOptions, startRenderingPage, continueRenderingPage and stopRenderingPage
 *
 * @param[in] bitmapContext	Reference to a bitmap context, as the rendering device.
 * @param[in] page			Reference to a page reference. The page has to be parsed first.
 *            
 * @param[out] renderer		Reference to a renderer.
 * @return	::kFGSErrorSuccess means rendering successfully finished.<br> 
 *			For more definitions please see definitions <b>FGSErrorRet</b>.
 *
 *
 */
FGSErrorRet FGSPDFPageCreatePageRenderer(CGContextRef bitmapContext, FGSPDFPageRef page, FGSDPRenderRef *renderer);
    
/**
 * @brief Set fore and background color.
 *
 * @param[in] renderer      Reference to a renderer.
 * @param[in] backColor     The background Color, in ABGR order.
 * @param[in] foreColor		The foreground Color, in ABGR order.
 *
 * @return	::kFGSErrorSuccess means set optons successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFPageRenderPageSetOptions(FGSDPRenderRef renderer, UInt32 backColor, UInt32 foreColor);

/**
 * @brief Start rendering of a page.
 *
 * @details Rendering is a progressive process. This function starts the rendering process,
 *			and may return before rendering is finished, if a pause structure is provided.<br>
 *			The application should call ::FGSPDFPageContinueRenderingPage repeatedly to finish the rendering 
 *			when return value is ::kFGSErrorToBecontinued.<br>
 *			There can be only one rendering procedure for a page at any time. And rendering
 *			can be started over and over again for the same page. If a page rendering is already
 *			active, starting another one will cancel the previous rendering.<br>
 *			Rendering of a page doesn't draw the page background, therefore, you usually need
 *			to draw the background in the CGContext yourself.<br>
 *			You don't have to parse the page before you can render it. The engine will parse
 *			the page along with the rendering process. With this technique, along with
 *			::kFGSPDFRenderDropObjects flag, you can really render very complicated pages without
 *			much memory consumption (because no page objects will be cached).
 *
 * @param[in] renderer		Reference to a renderer.
 * @param[in] matrix		The transformation matrix from page coordinates to device coordinates.
 * @param[in] rotate		The page orientation: <br>
 *							<ul>
 *							<li>0: normal</li>
 *							<li>1: rotated 90 degrees clockwise</li>
 *							<li>2: rotated 180 degrees</li>
 *							<li>3: rotated 90 degrees counter-clockwise</li>
 *							</ul>
 * @param[in] flags			0 means normal display. This can also be the combination of macro definitions:<br>
 *							<ul>
 *							<li>::kFGSPDFRenderAnnot</li>
 *							<li>::kFGSPDFRenderLCDText</li>
 *							<li>::kFGSPDFRenderBGRStripe</li>
 *							<li>::kFGSPDFRenderDropObjects</li>
 *							<li>::kFGSPDFRenderNoWidget</li>
 *							</ul>
 * @param[in] clip			A ::CGRect structure of a clip rectangle (in DIB device coordinations),
 *							or NULL if no clipping is needed.
 * @param[in] pause			A ::FGSPause structure that can pause the rendering process.
 *							This can be <b>NULL</b> if no pausing is needed.
 *
 * @return	::kFGSErrorSuccess means rendering successfully finished.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FPDFPageStartRenderingPage(FGSDPRenderRef renderer,
                                CGAffineTransform *matrix, FGSPDFRenderFlag flags,
                                CGRect *clip, FGSPause *pause);

/**
 * @brief Continue the page rendering
 *
 * @details This function may return any time when the pause interface indicates 
 *			a pause is needed. The application can call ::FGSPDFPageContinueRenderingPage any number
 *			of times, until ::kFGSErrorToBecontinued is not returned.
 *
 * @param[in] renderer		Reference to a render get form FPDFPageStartRenderingPage.
 * @param[in] pause			A ::FGSPause structure that can pause the rendering process.
 *							This can be <b>NULL</b> if no pausing is needed.
 *
 * @return	::kFGSErrorSuccess means rendering successfully finished.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFPageContinueRenderingPage(FGSDPRenderRef renderer, FGSPause *pause);

/**
 * @brief Stop a draw processing
 *
 * @param[in] renderer		Reference to a render get form FPDFPageStartRenderingPage.
 *
 * @return	::kFGSErrorSuccess means stop the quick draw processing successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet	FGSPDFPageStopRenderingPage(FGSDPRenderRef renderer);

/**
 * @brief Get a rendering progress in percentage.
 *
 * @param[in] page			Reference to a Page.
 *
 * @return  An integer between 0 and 100 (inclusive) indicating the rendering progress.
 *			The result is just a rough estimation.<br>
 *			-1 means parameter error.
 */
SInt32 FGSPDFPageGetRenderingPageProgress(FGSDPRenderRef renderer);

/**
 * @brief Set the pixel count limit for using halftone when displaying image.
 *
 * @details By default, SDK displays all bitmaps using downsamping, which means
 *			if the image is shrinked onto the screen, only part of pixels will be picked
 *			and displayed. This saves a lot of calculation, especially for big images
 *			with millions of pixels. However the display quality can be bad. <br>
 *			In order to reach a balance between performance and quality, 
 *			the application can use this function to set a limit: 
 *			if the count of pixels in an image is more than this limit, then SDK will use downsampling for quick drawing; 
 *			otherwise, if the image has less pixels, SDK will use halftoning for better quality.
 *
 * @param[in] limit	The count of pixels for the limit.
 *
 * @return None.
 */
void FGSPDFPageSetRenderingPageHalftoneLimit(UInt32 limit);

/**
 * @brief Get the page label.
 *
 * @param[in] page			Reference to a Page.
 *
 * @return	The string of th page label, user should free the string by call CFRelease.
 *
 */
CFStringRef FGSPDFPageCopyPageLabel(FGSPDFPageRef page);

/**
 * @brief Get the index of the page by the specified page label.
 *
 * @param[in] document			Reference to a document.
 * @param[in] caseSensitivity	A boolean value used to decide whether to find the page label without case-sensitivity or not.
 * @param[in] pagelabel			A page label string to be found. 
 *
 * @return	The found page index..
 *
 */
SInt32 FGSPDFPageGetPageIndexFormLabel(FGSPDFDocumentRef document, Boolean caseSensitivity, CFStringRef pagelabel);
    
/**
 * @brief Get page rotation. One of following values will be set: 0(0), 1(90), 2(180), 3(270).
 *
 * @param[in] page			Reference to a PDF page.
 *
 * @return  The value of the PDF page rotation.
 * @note	The PDF page rotation is rotated clockwise.
 *		After using this method, the content in this page will be changed, but not loaded.
 *		You must call the ::FGSPDFPageLoadPage to reload the page.
 */
SInt32 FGSPDFPageGetRotation(FGSPDFPageRef page);

/**
 * @brief	Calculate content bounding box in PDF page.
 *
 * @param[in] page		Handle to a PDF page.
 * @param[in] mode		The mode to calculate page content bounding box, please refer to macro definitions <b>FGSPDFPageMarginMode</b>.
 *
 * @return  The rectangle of the page content bounding box in PDF space coordinate system.
 *
 * @note	To call this function, <i>page</i> should be parsed.
 */
CGRect FGSPDFPageCalcContentBBox(FGSPDFPageRef page, FGSPDFPageMarginMode mode);

#ifdef __cplusplus
};
#endif

#endif // __FGSPDFPAGE__
/**@}*/


